home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 326-350 / disk_350 / memmometer / mm.doc < prev    next >
Text File  |  1992-05-06  |  21KB  |  329 lines
  1. /*
  2.  *   Information for MM Version 2.10, 24-Mar-1990
  3.  *
  4.  *   MemMometer - A program hacked from Tom Rokicki's WFrags more or less...
  5.  *   (in fact, a heck of a lot) in the style of Peter Da Silva's "Gauge."
  6.  *   The program opens a narrow window with the same dimensions as the
  7.  *   disk capacity gadget found in the top-level workbench window for
  8.  *   a floppy volume.  The sizing gadget is like the one in Gauge; to
  9.  *   resize the window, just click the left mouse button over the "E".
  10.  *   The "F" is the program title in this rather short manifestation of
  11.  *   an Amiga Intuition window drag bar.
  12.  *
  13.  *   My bin copy of Gauge broke when I put a Michigan Insider in my A1000.
  14.  *   I did not have source for the Gauge program, so I conjured this one.
  15.  *   To my chagrin, MM 1.0 broke when I got a 2000 (more on that shortly),
  16.  *   so I can hardly wait to see what the 3000 does to this version...
  17.  *   Changes with this version include a Priority menu item, automatic
  18.  *   column configuration of from one to three columns, compatibility
  19.  *   with the eight-color workbench, and timing via VBLANK signals from
  20.  *   the timer.device, replacing the notorious Delay(arrrgh) function
  21.  *   suspected to be linked with the treacherous floppy disk track 40
  22.  *   wipeout syndrome.  With the 2.10 version, the colors have been set
  23.  *   to more closely conform with the CBM workbench colors, the warps
  24.  *   recognition algorithm has been modified to detect a bitwise logical
  25.  *   true condition (0xffffffff) in addition to the usual bitwise and
  26.  *   otherwise logical false condition (0x00000000), and the titled crash
  27.  *   warning requester has been simplified at the expense of getting just
  28.  *   the title "F", but with the gain of not having the dummy window under
  29.  *   the requester.
  30.  *   
  31.  *   MemMometer may be started from an icon, a CLI, or the Run command
  32.  *   from a CLI.  MM uses dynamic allocation for its display data, and
  33.  *   does its own resource tracking.  MM will surrender any resources
  34.  *   which it has successfully obtained from allocation requests if,
  35.  *   while MM is running, requested resources are denied.  This type
  36.  *   of fault (exit code 20) proceeds silently, and without prior notice.
  37.  *
  38.  *   Now for a run through MemMometer's menu mechanics.  MemMometer opens
  39.  *   with a non-interlaced-screen-height narrow window at the left side of
  40.  *   the Workbench screen.  The window width is the same as the width of the
  41.  *   capacity gauge which Workbench renders at the left side of the top
  42.  *   level window for a floppy volume.  As with Peter Da Silva's gauge, the
  43.  *   MemMometer has an E at the bottom of the window, and an F at the top.
  44.  *   The E and the F are respectively, the window sizing gadget, and the
  45.  *   window titlebar.  New this version, the sizing gadget color identifies
  46.  *   the program MODE, and the title color reveals the selected memory
  47.  *   configuration.  While MemMometer can and does automatically arrange
  48.  *   the window to suit the memory configuration, it depends on the user to
  49.  *   select appropriate memory size and address values via the menus.  The
  50.  *   menu style is the usual Amiga Intuition menu set; selection is achieved
  51.  *   by clicking the left mouse button while the mouse pointer is anywhere
  52.  *   within the program's window boundary, and then activating the menu bar
  53.  *   by holding down the right mouse button and sliding the mouse pointer
  54.  *   along the Workbench screen title bar at the top of the Workbench screen.
  55.  *
  56.  *   At the left side of the Workbench screen title is the Project Menu.  The
  57.  *   Project Menu has three options.  The first option is "Front", which is a
  58.  *   window-to-front command for the event that the MM window was partially
  59.  *   buried by the opening of new windows after MM was invoked.   If the
  60.  *   right mouse button is released while the mouse pointer is directly over
  61.  *   the Front menu item, the MM window will oblige by popping forward to an
  62.  *   unobstructed view.  The second menu option is the "Back" item, which
  63.  *   will move the MM window back behind any other windows that have been
  64.  *   opened on the Workbench screen (with exception of a backdrop window).
  65.  *   The third Project menu option is the "Quit" option, which directs MM to
  66.  *   close its window and release the AmigaDOS resources MM has allocated.
  67.  *   The normal return code is zero.
  68.  *
  69.  *   The second Intuition menu is the Setup menu.  There are two Setup menu
  70.  *   items.  The first item is the "Mode" item.  MM has two modes, and they
  71.  *   are selected by sliding the mouse pointer straight down from the screen
  72.  *   title bar over the Mode item , and then moving the pointer to the right
  73.  *   as the mode submenu is activated.  The activated submenu provides two
  74.  *   choices, "Frags" and "Warps".  Frags are rather much the same as they
  75.  *   were in Da Silva's gauge program.  "Frags" is the default menu selection
  76.  *   with which MM is first initialized.  The Frags display is described in
  77.  *   the following table:
  78.  *   
  79.  *               2-Color Workbench    4-Color Workbench    8-Color Workbench
  80.  *  Unallocated        Blue                 Black                Black
  81.  *  Allocated          White                Orange               Yellow
  82.  *  Fragmented         Blue                 Blue                 Blue 
  83.  *
  84.  *   Unallocated memory is free memory available to programs.  The programs
  85.  *   may obtain this memory from AmigaDOS through allocation requests.  The
  86.  *   Allocated memory is memory assigned to programs running under AmigaDOS.
  87.  *   Fragmented memory consists of interleaved small memhunks, some of which
  88.  *   are assigned to programs and some of which are in the free memory pool.
  89.  *   The smallest fragments are 8 bytes, and the largest memhunks may be more
  90.  *   than a megabyte.  The fragmented class is assigned when, in making the
  91.  *   MM window display, a single horizontal pixel line was found to represent
  92.  *   both allocated and unallocated memhunks.  For this reason, for a full
  93.  *   window height MemMometer, the resolution of the fragmentation is shown
  94.  *   in more detail on interlaced Amiga Workbench screens.
  95.  *
  96.  *   The second mode item selection is the "Warps" mode.  While the Frags
  97.  *   mode is usually utilized as a low-priority background indicator, the
  98.  *   Warps mode is usually utilized at a somewhat higher priority for the
  99.  *   purpose of tracking bugs and system irregularities.  In this context,
  100.  *   I define warps as a form of discretized sample-to-sample differencing
  101.  *   function for some arbitrary segment of memory.  Warps are determined by
  102.  *   dividing the selected address space evenly among the MemMometer display
  103.  *   pixels, computing an assignment checkfunction for each pixel line of the
  104.  *   display on the associated assigned memory space at some sample time, and
  105.  *   then, while retaining the previous pixel-by-pixel record, repeating the
  106.  *   same evaluation the second sample time and comparing the sequentially
  107.  *   determined checksums. A "checksum" is computed by means of a sequential
  108.  *   bit-wise eXclusive OR assignment.  This type of checksum can readily
  109.  *   detect zeroed or changed values.  In the table below, logical FALSE is
  110.  *   zero, logical TRUE is taken as 0xffffffff and VALUE is anything else.
  111.  *   Colors indicate the type of change.  Colors for the most part follow
  112.  *   the standard CBM workbench color set, shown as follows:
  113.  *   
  114.  *                    Pen #   Color           Pen #   Color
  115.  *                      0     Blue              4     Green
  116.  *                      1     White             5     Red
  117.  *                      2     Black             6     Cyan
  118.  *                      3     Orange            7     Yellow
  119.  *
  120.  *   These colors are used to map the changes in memory content from sample
  121.  *   to sample as programs multitask together:
  122.  *
  123.  *   Condition        2-Color Workbench  4-Color Workbench  8-Color Workbench
  124.  *
  125.  *   VALUE ===> VALUE         Blue               Blue               Blue
  126.  *   VALUE =/=> VALUE         White              Orange             Orange
  127.  *   FALSE ===> FALSE         Blue               Black              Black
  128.  *   FALSE ---> VALUE         White              Orange             Yellow
  129.  *   VALUE ---> FALSE         White              White              Red
  130.  *   TRUE  ---> FALSE         Blue               Black              Cyan 
  131.  *   TRUE  ---> VALUE         Blue               Black              Cyan 
  132.  *   TRUE  ===> TRUE          Blue               Blue               Green
  133.  *   FALSE ---> TRUE          Blue               Blue               Green
  134.  *   VALUE ---> TRUE          Blue               Blue               Green
  135.  *
  136.  *   The second Setup menu item is a Frequency selection submenu.  While the
  137.  *   selected value does set a minimum frequency with which the memory state
  138.  *   will be examined, it's done by introducing a delay between measurements.
  139.  *   The introduced delay will be equal in seconds to the value selected in
  140.  *   the submenu.  The delay is accomplished by the AmigaDOS timer.device
  141.  *   using the VBLANK mode.  It was not thought worth the difficulty to make
  142.  *   the timing as precise as would be possible using the cia.resource, as
  143.  *   that might make the resource less useful to other programs, and as well
  144.  *   would mean extra effort adjusting for memory size-dependent scan times
  145.  *   from the various memory sizes selectable with the MM program.  Delay
  146.  *   intervals of 1, 2, 5, and 10 seconds are available.
  147.  *
  148.  *   The third Intuition menu is a Priority menu.  This menu applies only to
  149.  *   the MemMometer program and its associated CLI process.  Initially it is
  150.  *   at priority 0 with the expectation that the user will set it lower once
  151.  *   the program is running, in order to give more time to the other active
  152.  *   processes the user will be running.  A value of -50 is recommended.  In
  153.  *   the event the Priority of MM is changed via the menu, the CLI inherits
  154.  *   MemMometer's new priority and retains that priority even after MM quits.
  155.  *   Thus, with extreme priority settings, it may be better to "Run MM" to
  156.  *   keep from passing the extreme priority to subsequent processes spawned
  157.  *   from the CLI that was used to invoke MemMometer.  Also, go easy with the
  158.  *   positive priorities; remember that with AmigaDOS version 1.3 the DOS
  159.  *   input.device runs priority 20, FileSystem is priority 10, and the CON:
  160.  *   and trackdisk.device are priority 5 usually.  The first three menu items
  161.  *   are used to increment or decrement a selected priority.  Selection of
  162.  *   the "NORM" menu item removes any increment or decrement setting.
  163.  *
  164.  *   The remaining Intuition menu selections are provided so that the range
  165.  *   and base address of the memory examined may be adjusted for the user's
  166.  *   Amiga memory configuration.  Note that the base address must always be
  167.  *   set to the correct base address for the given memory configuration, but
  168.  *   that the range may be adjusted to give a better resolution for the first
  169.  *   segments above the base address, if desired.  Menus are provided for
  170.  *   Chip memory, Slow-Fast (C00000/Ranger) memory, and Fast memory.  While I
  171.  *   have had no difficulty as a result of selecting a range of memory that
  172.  *   involved a non-existent seqment for Chip or Fast memory, when I selected
  173.  *   non-existent SFMemory on my Fat Agnus Amiga 2000, it resulted in a total
  174.  *   system-wide big red Guru 4 (illegal instruction exception).
  175.  *
  176.  *   After that, I decided to post a requester for the user that issues a
  177.  *   terse a warning that a crash is _possible_ with incorrectly specified
  178.  *   Slow-Fast (non-existent) memory.  Since it is possible to access this
  179.  *   forbidden zone through inappropriate settings of the Fast Mem base, MM
  180.  *   also calls the requester if the Fast Mem base is changed. The requester
  181.  *   displays the message:
  182.  *
  183.  *                        WARNING! CRASH POSSIBLE
  184.  *                      MENU MEMORY SELECTIONS MUST
  185.  *                       REFERENCE EXISTING MEMORY
  186.  *
  187.  *                   Risk It                  Retreat
  188.  *
  189.  *   You don't have to worry about a crash if you really have an amount of
  190.  *   Slow-Fast memory equal or greater than the amount you specified in the
  191.  *   menu selection, and the base address is what you specified (the default
  192.  *   base address is C00000).  I'm sorry to have to do this, but I don't want
  193.  *   to put in code that monkeys with AmigaDOS's handling of the exception
  194.  *   vectors.  I feel justified, though, since my code does not change with
  195.  *   the type of memory segment examined; AmigaDOS evidently does have code
  196.  *   that handles the exceptions properly for the other memory segments.
  197.  *   So, here you see the two options.  The left button says - Risk It - a
  198.  *   comfortable gamble if you know your Slow-Fast memory configuration.
  199.  *   Pre Fat-Agnus Amiga 2000 machines have 512K of Slow-Fast memory.  Newer
  200.  *   Amiga 2000 machines have no Slow Fast memory - so beware of this and try
  201.  *   it when you have nothing else going on.  The - Retreat - option sets
  202.  *   the SFMemory Size internal to the MemMometer program to zero and clears
  203.  *   the display.  (It does leave the menu items checked, though, so you will
  204.  *   have to remember to re-select suitable menu values in order to get the
  205.  *   display to show something in each existing memory type.  For Chip and
  206.  *   Fast memory this will simply entail going back into the menu and again
  207.  *   selecting whatever was previously checked.  The Slow-Fast memory size
  208.  *   should then be set either to appropriate values or to "NONE".)
  209.  *   
  210.  *   Note that in the display there may at any time be anywhere from one
  211.  *   to three MemMometers - for Chip (left-hand column), another for the
  212.  *   Slow Fast mem (center column) and yet another for Fast mem (right-hand
  213.  *   column).  These MemMometers can be turned on or off as desired by
  214.  *   selecting "NONE" or the various items in the Size menus.
  215.  *
  216.  *   Parts of several freely distributable  programs have been used to make
  217.  *   MemMometer.  Menus, for instance, are done in the style VT100 (Wecker,
  218.  *   et al).  As with the VT100 program, MemMometer has preset variables.
  219.  *   However, the program does not yet contain a script file reader or an
  220.  *   AREXX interface with which to automatically set the variables.  Likely
  221.  *   it is that I'll write the code for that some time this century!
  222.  *
  223.  *   MemMometer uses forbid() and permit() when it examines the mem list in
  224.  *   Frags mode.  I suppose it is possible with large amounts of memory to
  225.  *   scan, that some gross treachery can happen while the list is locked.
  226.  *   However, with my 3 meg Amiga 2000 I've not seen it.  It takes a while
  227.  *   after startup to settle out and display the large byte counts associated
  228.  *   with Fast mem, so be patient...  MemMometer is most useful for finding
  229.  *   out why large programs won't load.  It's also useful in development for
  230.  *   seeing the impact your application is having on memory fragmentation.
  231.  *   The Warps mode displays any change it sees in memory from one sample
  232.  *   to the next; BUT this mode only works sensibly when JUST ONE memory size
  233.  *   selection is active (set others to "NONE").  The memory space is scanned
  234.  *   asynchronously, so it can have sample alias difficulties.  However, the
  235.  *   Warps mode does not use forbid(), permit(), enable(), disable(), or any
  236.  *   other constrictive system call.  I just does a lot of read-only memory
  237.  *   cycles and writes the result in its own dynamically allocated memory
  238.  *   space.
  239.  *
  240.  *   To run MemMometer, simply type
  241.  *
  242.  *      run MM
  243.  *
  244.  *      or  click on the icon.
  245.  *
  246.  *   Then open the menu item selections and set them for your configuration.
  247.  *   Frags mode, and 512K of CHIP @0, 0 Meg of Fast mem @ 200000, 0 Meg of
  248.  *   SF mem @ @C00000 are the defaults.  The modes selected are color coded
  249.  *   into the "F" and "E" indicators:
  250.  *
  251.  *   Mode       Indicator       2 color WB      4 Color WB      8 Color WB
  252.  *
  253.  *   Frags          E                Blue            Blue            Blue
  254.  *   Warps          E                White           Orange          Yellow
  255.  *
  256.  *   One column:
  257.  *   Chip           F                Blue            Blue            Blue  
  258.  *   Slow-Fast      F                Blue            Black           Cyan
  259.  *   Fast           F                White           Orange          Yellow
  260.  *
  261.  *   Two columns:
  262.  *   Chip +SF       F                Blue            Blue            Blue
  263.  *   Chip +Fast     F                Blue            Black           Cyan
  264.  *   SF + Fast      F                White           Orange          Yellow
  265.  *
  266.  *   Three columns:
  267.  *   C + SF + Fast  F                Blue            Blue            Blue
  268.  *   None           F                White           Orange          Orange
  269.  *
  270.  *   The source code included with this distribution was compiled with the
  271.  *   Manx Aztec C compiler, version 3.6a in 16-bit integer mode.  Numerous
  272.  *   type casts in the code, as well as other non-alignments with the Lattice
  273.  *   environment would make compilation under versions of Lattice difficult.
  274.  *   Sorry.  Compilation instructions are of course in the makefile included
  275.  *   in the distribution.
  276.  *
  277.  *   About my part of C code - it wasn't done for speed, as I am sure you can
  278.  *   tell.  If I wanted speed I would have used assembly language.  It also
  279.  *   likely isn't elegant code, by a long shot (unless it's the part I got
  280.  *   from Rokicki's WFrags).  But assembly language is time-consuming to
  281.  *   write, so that won't happen any time soon.  Maybe the next thing will be
  282.  *   the AREXX port - so that other programs can specify a low address and a
  283.  *   byte count range for one of the MemMometers to display (say, within the
  284.  *   specified menu selection span).  Gross comments about the code or bug
  285.  *   reports may be e-mailed to me at the site domain specified below.
  286.  *
  287.  *   About everyone else's C code in MM - Let's see, VT100 (Wecker et al) has
  288.  *   been freely distributable since the early days of the Amiga.  When VT100
  289.  *   was first posted, Wecker did not prepend a copyright to the code.  He
  290.  *   later discovered that his employer (DEC) routinely required employees to
  291.  *   sign a contract statement which granted to DEC all rights with respect
  292.  *   to codes written by DEC employees, whether the codes were written on the
  293.  *   company's time/facilities or otherwise.  I do not know how the matter
  294.  *   was resolved, but VT100 still seems to be on the freely distributable
  295.  *   software list; the VT100 codes, now with parts from many contributors,
  296.  *   are currently maintained by Antony C. Sumrall (acs@ahmdahl.com).  The
  297.  *   menus in MM, while styled with the same code forms as were used with
  298.  *   VT100 v2.3, are of course different in content in any case.  The WFrags
  299.  *   program was, I believe, a version by Tom Rokicki (the Amiga Tex guy)
  300.  *   probably evolved from the Frags program originally submitted to the net
  301.  *   by Mike Meyer.  WFrags was submitted to the net without a prepended
  302.  *   copyright notice, evidently intended  as freely distributable software.
  303.  *
  304.  *   The spirit of these contributions is that they are not to be used for
  305.  *   commercial purposes, and the original authors certainly appreciate
  306.  *   being cited for their work.  So I just did that.  The timer codes are
  307.  *   exerpted from a network article by Andy Finkel of CBM, submitted as a
  308.  *   demonstration of the ease of implementing the Amiga timer.device in C.
  309.  *   There are supposedly at least two ways to implement the timer.device,
  310.  *   either as a message port to the Amiga Exec, or as an IDCMP feature in
  311.  *   Amiga Intuition.  It would seem that the latter would be better for a
  312.  *   program (such as this one) which makes resolute use of Intuition IDCMP
  313.  *   features.  However, Andy's code was for the former, and rather than do
  314.  *   whatever would have been required to utilize the IDCMP TIMER flag, I
  315.  *   just went with what Andy originally wrote.  So, for my part, I add no
  316.  *   further restrictions to the codes in MM, though I expect everyone must
  317.  *   regard the MM code as owned by Rokicki - even if he is not in any way
  318.  *   responsible for maintaining the codes or controlling the result of their
  319.  *   use.  Thus, I submit the following Standard Disclaimer:
  320.  *
  321.  *   The authors accept no responsibility for anything either beneficial or
  322.  *   detrimental that may happen as a result of using the codes in MM.  The
  323.  *   codes are intended for non-commercial use only.
  324.  *   
  325.  *
  326.  *   Howard Hull  hull@ncar.ucar.edu
  327.  *
  328.  */
  329.